41.2 emacsclient Options

You can pass some optional arguments to the emacsclient program, such as:

emacsclient -c +12 file1 +4:3 file2

The ‘+line’ or ‘+line:column’ arguments specify line numbers, or line and column numbers, for the next file argument. These behave like the command line arguments for Emacs itself. See Action Arguments.

The other optional arguments recognized by emacsclient are listed below:

‘-a command’

‘--alternate-editor=command’

Specify a command to run if emacsclient fails to contact Emacs. This is useful when running emacsclient in a script.

As a special exception, if command is the empty string, then emacsclient starts Emacs in daemon mode (as emacs --daemon) and then tries connecting again.

The environment variable ALTERNATE_EDITOR has the same effect as the ‘-a’ option. If both are present, the latter takes precedence.

‘-c’

‘--create-frame’

Create a new graphical client frame, instead of using an existing Emacs frame. See below for the special behavior of C-x C-c in a client frame. If Emacs cannot create a new graphical frame (e.g., if it cannot connect to the X server), it tries to create a text terminal client frame, as though you had supplied the ‘-t’ option instead.

On MS-Windows, a single Emacs session cannot display frames on both graphical and text terminals, nor on multiple text terminals. Thus, if the Emacs server is running on a text terminal, the ‘-c’ option, like the ‘-t’ option, creates a new frame in the server’s current text terminal. See Windows Startup.

If you omit a filename argument while supplying the ‘-c’ option, the new frame displays the *scratch* buffer by default. You can customize this behavior with the variable initial-buffer-choice (see Entering Emacs).

‘-F alist’

‘--frame-parameters=alist’

Set the parameters for a newly-created graphical frame (see Frame Parameters).

‘-d display’

‘--display=display’

Tell Emacs to open the given files on the X display display (assuming there is more than one X display available).

‘-e’

‘--eval’

Tell Emacs to evaluate some Emacs Lisp code, instead of visiting some files. When this option is given, the arguments to emacsclient are interpreted as a list of expressions to evaluate, not as a list of files to visit.

‘-f server-file’

‘--server-file=server-file’

Specify a server file for connecting to an Emacs server via TCP.

An Emacs server usually uses a local socket to listen for connections. Some operating systems, such as Microsoft Windows, do not support local sockets; in that case, the server communicates with emacsclient via TCP.

When you start a TCP Emacs server, Emacs creates a server file containing the TCP information to be used by emacsclient to connect to the server. The variable server-auth-dir specifies the directory containing the server file; by default, this is ~/.emacs.d/server/. To tell emacsclient to connect to the server over TCP with a specific server file, use the ‘-f’ or ‘--server-file’ option, or set the EMACS_SERVER_FILE environment variable.

‘-n’

‘--no-wait’

Let emacsclient exit immediately, instead of waiting until all server buffers are finished. You can take as long as you like to edit the server buffers within Emacs, and they are not killed when you type C-x # in them.

‘--parent-id id’

Open an emacsclient frame as a client frame in the parent X window with id id, via the XEmbed protocol. Currently, this option is mainly useful for developers.

‘-q’

‘--quiet’

Do not let emacsclient display messages about waiting for Emacs or connecting to remote server sockets.

‘-s server-name’

‘--socket-name=server-name’

Connect to the Emacs server named server-name. The server name is given by the variable server-name on the Emacs server. If this option is omitted, emacsclient connects to the first server it finds. (This option is not supported on MS-Windows.)

‘-t’

‘--tty’

‘-nw’

Create a new client frame on the current text terminal, instead of using an existing Emacs frame. This behaves just like the ‘-c’ option, described above, except that it creates a text terminal frame (see Non-Window Terminals).

On MS-Windows, ‘-t’ behaves just like ‘-c’ if the Emacs server is using the graphical display, but if the Emacs server is running on a text terminal, it creates a new frame in the current text terminal.

The new graphical or text terminal frames created by the ‘-c’ or ‘-t’ options are considered client frames. Any new frame that you create from a client frame is also considered a client frame. If you type C-x C-c (save-buffers-kill-terminal) in a client frame, that command does not kill the Emacs session as it normally does (see Exiting). Instead, Emacs deletes the client frame; furthermore, if the client frame has an emacsclient waiting to regain control (i.e., if you did not supply the ‘-n’ option), Emacs deletes all other frames of the same client, and marks the client’s server buffers as finished, as though you had typed C-x # in all of them. If it so happens that there are no remaining frames after the client frame(s) are deleted, the Emacs session exits.

As an exception, when Emacs is started as a daemon, all frames are considered client frames, and C-x C-c never kills Emacs. To kill a daemon session, type M-x kill-emacs.

Note that the ‘-t’ and ‘-n’ options are contradictory: ‘-t’ says to take control of the current text terminal to create a new client frame, while ‘-n’ says not to take control of the text terminal. If you supply both options, Emacs visits the specified files(s) in an existing frame rather than a new client frame, negating the effect of ‘-t’.